Authorising use of a computer program

ABSTRACT

A method of authorising use of a computer program only able to be used when an authorised message is received from an authorising system includes providing an authorisation system, making a request to use a computer program, signalling the request to the authorisation system, the authorisation system recording the use of the computer program and providing the authorisation message to the computer program upon receipt of the authorisation message the computer program may be used.

This application is a continuation of U.S. Ser. No. 12/730,679, filed 24Mar. 2010, which is a continuation of U.S. Ser. No. 10/240,207, filed 23Apr. 2003, which is a national stage application of PCT/AU2001/00350,filed 28 Mar. 2001, which claims benefit of PQ 6544, filed 28 Mar. 2000in Australia and which applications are incorporated herein byreference. To the extent appropriate, a claim of priority is made toeach of the above disclosed applications.

FIELD OF THE INVENTION

The present invention relates to authorising use of a computer program,in particular the present invention relates to a method of authorisinguse of a computer program, a computer configured to authorise the use ofa computer program and a computer readable media on which is storedcomputer software for authorising use of a computer program.

BACKGROUND OF THE INVENTION

There is an increasing need for securing and protection of computerprograms and other digital products. This is reflected in an increasingdemand for a “pay as you use” payment arrangement for licensed use ofcomputer software. It is known for a server to provide applicationsoftware to a plurality of client's machines. Under this model it ispossible to provide a “pay as you use” method of software licensing.Current pricing models used for the payment of software applications arebased on per user and seat licensing agreements that are complex,restrictive and inefficient, especially for client server andapplication service provider software delivery. “Pay as you use” pricingis demanded by software users for its simplicity, cost effectiveness andflexibility.

There is therefore a need for an alternative method of providing asoftware licensing system that allows for each user of the software tocorrespond a payment for that use. The licensed software needs to beable to be prevented from use unless authorised, to allow for inter aliapayment for using the software.

SUMMARY OF THE PRESENT INVENTION

An object of the present invention is to provide a method of authorisinguse of a computer program in a manner suitable for implementing interalia a “pay as you use” licensing system.

According to the present invention there is provided a method ofauthorising use of a computer program, said method including the stepsof:

-   -   providing an authorisation system;    -   recording an identifier of a computer program to be authorised        for use with the authorisation system;    -   a user registering with the authorisation system and receiving a        user identification from the authorisation system;    -   the user making a request to use the computer program;    -   the computer program identifier and user identification being        sent to the authorisation system in a login request message;    -   the authorisation system verifying the identity of the user from        the user login identification and checking that the user is        authorised to use the computer program identified by the        computer program identifier;    -   the authorisation system recording the information sent with the        request message;    -   if the user is verified and authorised to use the computer        program, then a login authorisation message is sent to the        computer program, otherwise an authorisation denied message is        sent to the computer program;    -   whereby upon receipt of the authorisation message the computer        program may be used by the user.

Preferably the method includes the steps of:

-   -   the computer program sending a request to the authorisation        system to incur a charge for the use of the computer program;    -   the authorisation system recording a charge against the        identified user for use of the computer program.

Preferably the authorisation system records whether the user isverified, whether the user is authorised to use the computer program anda time stamp.

Preferably the computer program may be a software application or asub-component of a software application.

Preferably the charge for use of the computer program is recorded inusage units.

Preferably a rate of charging usage units for the use of the computerprogram is recorded in the authorisation system. A different rate ofcharge may be applied to different computer programs.

Preferably the usage units are charged by the authorisation system uponreceipt of the request to charge for the use of the computer program.

Preferably the request to the authorisation system for charge of usageunits is sent once per use of the computer program. Alternatively therequest to the authorisation system to charge usage units is sent onceper specified period during the use of the computer program.

Preferably the user purchases usage units in advance of use of thecomputer program, the usage unit total being reduced by each charge, usebeing authorised only while there are a positive number of usage unitsleft.

Preferably the authorisation message is encrypted. Preferably, thecommunication between the interface program and the authorisation systemis encrypted. Preferably messages to and from the authorisation systemincludes a unique component that is only valid for a single use, so thatthe message can't be duplicated and used again.

Preferably the user identification is obtained from the user byproviding the user with a login prompt, the user entering the loginidentification provided by the authorisation system, the entered useridentification being included in the login request.

Preferably an interface program signals the login request to theauthorisation system. Preferably the interface program is a separateprogram called by the computer program being authorised as part of theinitialisation of the authorised computer program. In one embodiment theinterface program forms part of the computer program and is started whena user attempts to use the computer program. In another alternativeembodiment, the interface program is part of an operating system and isstarted when a user attempts to use the computer program.

Preferably the authorisation system is at a location remote from acomputer running the activated computer program. More preferably, thecomputer running the activated computer program also runs the interfaceprogram, the interface program communicates with the authorisationsystem over a computer network.

Preferably the authorisation system is configured to record andauthorise a plurality of computer programs. Typically, the authorisationsystem is configured to record and authorise a plurality of uses of thesame computer program.

In one embodiment the authorisation is provided for each activation ofthe computer program. Typically, a charge is generated for each use ofthe computer program. In another embodiment, the authorisation isrequired periodically, wherein at the end of a period of time specifiedin the computer program from the last authorisation, a request to chargethe usage units is sent to the authorising system for a furtherauthorisation, the authorisation system sends each further authorisationand records the use for each period, whereby a charge is generated foreach authorisation message sent.

In yet another embodiment, when the computer program is finished, aterminate message is sent to the authorisation system, the authorisationsystem records the duration of the use of the computer program betweenwhen the authorisation message is sent to the computer program until theterminate message is received, whereby a charge in PUs is generated foruse of the computer program corresponding to the recorded duration.

According to another aspect of the present invention there is provided adistributed system for authorising use of a computer program, saidsystem comprising at least:

-   -   an authorisation system, with a storage means for recording an        identifier of a computer program to be authorised for use with        the authorisation system and recording a user identification;    -   a computer for running the computer program;    -   the computer being configured to send the identifier of the        computer program and user identification to the authorisation        system in a login request message when the user makes a request        to use the computer program;    -   the authorisation system being configured to verify the identity        of the user from the recorded user login identification and        check that the user is authorised to use the computer program        identified by the recorded computer program identifier;    -   the authorisation system configured to record the information        sent with the request message;    -   the authorisation system being configured to send a login        authorised message to the computer if the user is verified and        authorised to use the computer program and otherwise send an        authorisation denied message to the computer;    -   whereby the computer is configured to continue use of the        computer program upon receipt of the authorisation message but        otherwise terminate the use of the computer program.

Preferably the computer is configured to sending a request to theauthorisation system to record a charge or the use of the computerprogram against the identified user for use of the computer program.

Preferably the computer storage means records the rate of charge for theuse of the computer program

Preferably the authorisation system records a charge against the userupon receipt of the request to charge for use of the computer program.

Preferably the computer is configured to send a request to theauthorisation system to charge the user once per use of the computerprogram.

Preferably the computer is configured to send a request to theauthorisation system to charge the user is sent once per specifiedperiod during the use of the computer program.

Preferably the computer is the communication between the computerprogram and the authorisation system is encrypted.

Preferably the computer and authorisation system are configured toinclude a unique component in the encrypted messages communicatedtherebetween.

Preferably the authorisation system is at a location remote from acomputer running the activated computer program.

Preferably the computer running the activated computer program also runsthe interface program, an interface program that communicates with theauthorisation system over a computer network.

Preferably the authorisation system is configured to record andauthorise a plurality of computer program.

BRIEF DESCRIPTION OF THE DRAWINGS

In order to provide a better understanding, preferred embodiments of thepresent invention will now be described in detail, by way of exampleonly, with reference to the accompanying drawings, in which:

FIG. 1 is a schematic representation of a system that enables theauthorisation of use of a computer program in accordance with thepresent invention;

FIG. 2 a is a state diagram showing the states of a server waiting for alogin;

FIG. 2 b is a state diagram showing the states of a run time licenceconsumption session;

FIG. 3 is a flow chart showing the method of the present invention;

FIG. 4 is a schematic timing diagram of message passing betweencomponents of the system of FIG. 1;

FIG. 5 is a schematic timing diagram of an alternative method of messagepassing between components of the system of FIG. 1; and

FIG. 6 is a flow chart showing the registration of a user and a softwareapplication for use with the present invention.

DETAILED DESCRIPTION OF PREFERRED EMBODIMENTS

Referring to FIG. 1, a system 10 is shown for authorising use of acomputer program, such as a software application 12 on a computer 14.The computer program may be a sub-component of a larger softwareapplication. A user 5 activates the software application 12 forexecution on the computer 14. The software application 12 calls aninterface program 16, known as a Software Application Interface Libraryprogram (SAIL). The SAIL 16 communicates with an on-line server 18 via anetwork, such as the Internet 20. An authorisation system 22 is runningon the server 18. The authorisation system 22 is called a SoftwareApplication Licence Manager Over Networks (SALMON) system. It is notedthat the computer platform need not be the same as the server, likewiseoperating systems of the computer and the server need not be the same.The SALMON system 22 is able to handle many software applications on aplurality of computers, each having a SAIL interfacing with the SALMONsystem 22 via a communication network, such as the Internet 20. TheSALMON system 22 communicates with the SAIL 16 to determine whether theuser is authorised to use the software application 12. There is a one toone relationship between the user and the instance of the softwareapplication. This allows for each user to be charged for each use of thesoftware application.

The SAIL 16 is provided to a software vendor that wishes to use thesystem 10 of the present invention. The software vendor incorporatescalls to the SAIL 16 in the vendor's computer program.

The computer program or software application 12 is written to bedisabled from use until the user 5 is identified to the SALMON system 22using a login routine of the SAIL 16 and receives an authorisationmessage from the SALMON system 22. The authorisation message operates asa once off run time licence. The SAIL 16 sends another authorisationmessage to the software application 12 when it receives the authorisedmessage from the SALMON system 22.

Specifically, when the software application is started, it calls a loginsub-routine of the SAIL 16. The application waits for the SAIL loginsub-routine to return a message indicating that the user is logged in. Asoftware vendor wanting to charge for use of the software can decide theprice of use. It may be free, parts of the software may be charged for,or all of the software may be charged for. The cost may be charged oneach start-up of the application, on a time basis or on a per functionbasis. Different users may be charged different rates. A user is chargedfor using a program use run-time licence unit (RTL). The SAIL 16, oncelogged in, can send a message to the SALMON system 22 to record usage ofthe computer program/software application according the payment schemedesired.

Referring to FIG. 3, which shows the operation of the present inventionin the form of a flow chart. The flow chart starts at 202 where a userwishes to run a software application. The user activates the softwareapplication in the normal manner at 204. The software applicationinterfaces with the SAIL 16 to validate the user at 206 via a loginrequest message which is encrypted with a public key at 208 by the SAIL16. The encrypted login request message is communicated over a network210, such as the internet, and is then decrypted with a private key at212 in a server running the SALMON system 22. The SALMON system 22validates the user name, password and the status of the application at214. If the user is valid and authorised to use the softwareapplication, a logged-in confirmation message is encrypted with a publickey at 216 and sent across the network 210. It is decrypted at 218 witha private key by the SAIL 16.

If the validation is successful, as indicated by 220, the applicationcontinues at 222. If the software vendor wishes the user to pay for theuse of the software application, the steps from 224 take place. Theaccount creditability is validated at 226. The SAIL 16 sends a publickey encrypted “allocate a charge” message at 228 over the network 210.The message is then decrypted with a private key at 230. The account ischecked to determine whether sufficient RTLs are available. If so, therequired number of RTLs are debited at 232. A charged confirmationmessage is encrypted with a public key and sent at 234 across thenetwork 210 and decrypted at 236 with a private key. If the validationis successful the application continues at 238, otherwise it terminatesat 240.

The method of encryption of transmitted messages involves the inclusionof a unique component so that a message is valid only once. Each messageis in the form of a binary number to be sent between the SAIL 16 and theSALMON system 22. A random number is added to the message. A digestionroutine takes the data from the message and the random number to producea digestion value. The digestion value is computed in such a way thatfinding an input that will exactly generate a given digest iscomputationally infeasible. The message data, the random number and thedigestion value are then encrypted using a public key. The message isthen transmitted. The received message is then decrypted using a privatekey. The decrypted message is then separated in to individualcomponents. The message can be validated by using the same digestionformula on the message and random number components to check thedigestion result calculated against the digestion value received. If thevalues are the same the message is considered valid, otherwise it isconsidered invalid. This process provides a different data sequence foreach message even if the same acknowledgment message is sent each time.In this way each message includes a unique value which can only be usedonce. Thus if the message is duplicated it will no longer by valid andwill be rejected.

The SALMON system 22 may be configured to allow many users to beauthorised at the same time for one or more software application. Thesoftware vendor may allow up to a predetermined number of users to loginfor a particular software application. For each authorised user alloweda login a login resource is allocated in the SALMON system 22. Eachavailable login resource, a login daemon process will be waiting for auser to login.

Referring to FIG. 2 a, until a login is received each of the logindaemon processes remains in a not logged in state 30. Once a login 32 isreceived the SALMON system 22 enters a logged in state 34. A routine“Can consume RTL” 35 checks to see whether RTLs may be consumed, untilthe user 5 logs out at 38, whereupon the login resource of the SALMONsystem 22 re-enters the not logged in state 30. Thus checking thatsufficient funds (in the form of RTLs) are available can be a criterionfor authorisation.

FIG. 2 b shows the consumption of RTLs in the logged in state 34. Aroutine “ConsumeRTL” 42 consumes RTLs on the successful verification bySALMON system 22. If there are sufficient RTLs and it is a validtransaction. At the completion of the use of software applicationpending logout, or once all available RTLs are consumed, the user logsout 38.

A user of the software application using the on-line pay as you usemodel must first be registered with the on-line SALMON system 22. Theywill be provided with a user name and password so that the SALMON system22 can identify them and the login details verified.

The login of the user is to verify that the user is logged with theon-line SALMON system 22 before being able to proceed with use of thesoftware. The software application logs out from the SALMON system 22 inorder to provide a clean exit. Generally, only one login session peruser should be active, a previous session must be logged out beforeanother login session can begin.

Referring to FIG. 4, the passing of messages is now described. A user 5activates a software application 12 thereby creating 50 an instance ofthe software application 12. The software application 12 then creates 52an instance of the SAIL 16. The software application 12 requests detailsfrom the user 5 at 54. The user 5 enters a user name and password at 56.The software application calls a “SAIL-login” routine of the SAIL 16 at58. The SAIL 16 then establishes a connection, via the Internet 20, tothe SALMON system 22. The SAIL-login routine then passes the user name,password and an identification of the software to the SALMON system 22.Once confirming that the login details are correct, the SALMON system 22sends a login “OK” message at 62 to the SAIL 16 which then at 64 sendsan “OK” message to the software application 12.

Depending on the model that the software vendor wishes to use the chargefor use of the software an appropriate scheme of using RTLs will beused. The scheme described in relation to FIG. 4 is for a one-off chargefor use of the software application. Other schemes will be describedbelow.

The software application 12 then sends a one-off request to consume anRTL at 66. This request is a SAIL-consume RTL call. The SAIL-consume RTLsends a consume RTL message to the SALMON system 22 at 68. The SALMONsystem 22 records the request to consume RTL and sends an authorisationmessage at 70 to the SAIL 16. The SAIL 16 then passes the OK message at72 to the software application 12. The software application 12 thenbegins to log out of the SAIL 16 at 74. The logout message is thenpassed from the SAIL 16 to the SALMON system 22 at 76. A Logoutconfirmation message is then passed from the SALMON system 22 to theSAIL 16 at 78. The logout confirmation message is then sent from theSAIL 16 to software application 12 at 80. The software application 12may then terminate the SAIL program 16 at 82. The user 5 may proceedwith use of the software application 12 at 84. Once the user hasfinished with the software application 12 it may then be terminated at86.

The recording of the consumption of a one-off consumption of an RTLcreates a charge for the one-off use of the software application 12.This charge may be deducted from an amount of RTLs held in credit forthe user 5 or may be billed to the user 5.

Different software applications may request the consumption of differentnumbers of RTLs. For example a word processing application may consumefive RTLs whereas a spreadsheet may consume 10. As mentioned above, thesoftware being authorised need only be a sub-component of a largesoftware application. For example, a print function may be regarded asthe computer program being authorised. For each use of the printfunction a charge is accrued. A user 5 may also be entitled to adiscount such as, for example, if they are a high volume user. Thenumber of RTLs may then be multiplied by a user discount to produce afinal number of RTLs deducted from the user's account.

Referring to FIG. 5, the periodic consumption of RTLs is described.Periodic consumption of RTLs may be consumed at a different rate toone-off consumption of RTLs. Like numerals depict like actions from FIG.4. Again the user 5 starts the software application 50 which creates theinstance of the SAIL 16 at 52. Login is requested at 54 and logindetails are provided to the SAIL 16 at 56. The login details are thenpassed from the software application to SAIL 16 at 58 and then onto theSALMON system 22 at 60. The confirmation of login is passed from theSALMON system 22 to the SAIL 16 at 62, and from the SAIL 16 to thesoftware application at 64. The user may proceed with the normal use ofthe application at 84. In the meantime, the software application 12makes periodic requests to the SAIL 16 for the consumption of an RTL at98. The SAIL 16 passes the request to the SALMON system 22 at 100. Theconfirmation of the recording of the consumption of the RTL occurs inthe SALMON system 22 and the confirmation of this is then passed fromthe SALMON system 22 to the SAIL 16 at 102 and then from the SAIL 16 tosoftware application 12 at 104.

At the end of each period a further RTL is consumed as indicated by 106,108, 110 and 112. When the user has finished with the application, acommand is sent to exit from the application 12 at 86. The softwareapplication then sends the logout message to the SAIL 16 at 74 which isthe sent on at 76 to the SALMON system 22. Confirmation of the logout issent from the SALMON system 22 to the SAIL 16 at 78 and then from theSAIL 16 to the software application 12 at 80, whereupon the softwareapplication may end the instance of the SAIL 16 at 82 and then shutitself down.

As an alternative the software application 12 may specify the period tothe SAIL 16 and the SAIL 16 handles the operation of sending consume RTLmessages to the SALMON system 22 for deduction RTLs from the usersaccount.

The number of periodic RTLs consumed is recorded and a correspondingcharge generated. The total charge for the session is deducted from anaccount or billed out. RTLs may use currency units, the consumption ofRTLs is in itself payment. The charge for the consumption of each RTLcan be arranged by agreement between the software vendor and the systemoperator.

The SALMON system 22 may be configured to allow many users to beauthorised at the same time for one or more software applications. FIG.6 shows a flow chart setting out the establishment of a pay-as-you-useregistration according to the present invention. The flow chart beginsat 302 where a user wishes to use a software application utilising thesystem of the present invention. If the user is registered with theadministrators of the authorisation SALMON system 22 they proceed downpath 304 otherwise they need to register with the administrator, in thiscase “OPTIMISER” at 306. An on-line registration site is made availableover the Internet at 308, where the user can register to use a singlesoftware application 310 or a range of software applications 312. Asubscription fee is paid at 314 or 316 depending on whether the userselects a single software application or general use. A rate of, forexample US$10 per annum is paid if a single application is to be used.An annual subscription of, for example US$120 per annum is charged forgeneral use of software. Once this payment is made to the administratorthe process continues at 318 as if the person was previously registered.

If the user wishes to use an application that is not pay-as-you-useenabled as indicated at 320, the software vendor will need to registerthe system with the administrators. If the software is registered itwill proceed as indicated by 322. The software vendor may downloadwebsite software as indicated by 324. If the software vendor is notregistered with the administrator as indicated by 326 the vendor mustregister at 328. Once the vendor is registered the SAIL interfaceprogram can be downloaded at 330 and integrated into the vendor'ssoftware at 332.

Once the user is registered, the user must have credit available withthe administrator. This is checked at 334. If they don't, as indicatedby 336, they must purchase RTLs. If they have paid the vendor for usageas indicated by 338 the vendor must pass on the usage payment at 340 tothe administrator, which will be credited as RTLs. Once the user hasRTLs credited as indicated by 342 the user may use the softwareaccording to the present invention. When the software application isstarted the SAIL is activated at 344, as described above, with 344 beingequivalent to 50 in FIGS. 4 and 5. The authorisation of the user isindicated by 346 being the equivalent of the OK message 64 in FIGS. 4and 5. On-line usage reporting, indicated by 348, is equivalent to therecording of the logging in and consumption of RTLs. The user may thenview their access usage and RTL consumption at a later stage. Even ifthe software is not charged for use, the software can be recorded andtracked.

The SAIL interface 16 may provide a “heart beat” function thatperiodically sends the SALMON system 22 a message to check that aconnection between the two still exists. If the connection has droppedout, it may be re-established or the application terminated, dependingon the security desired by the software vendor.

A list of SAIL Application Program Interface (API) system calls islisted in appendix 1. A more preferred list of SAIL API system calls islisted in appendix 2. A set of example scenarios showing the use of theSAIL 16 is included in appendix 3.

The SAIL interface as implemented as an Application ProgrammableInterface (API) library able to interface with the programming languageof the software application. Programming methodologies like ActiveX orCORBA can be used to provide class wrappers around the system APIlibrary.

Now that the preferred embodiments have been described it will be clearto the skilled addressee that it has at least the following advantages.A locked software application may be provided to each user that is onlyable to be unlocked and used where the user purchases run time licenceswhich are consumed on a per use or time basis. This means that softwaredoes not need to be downloaded and may be provided on, for example, afloppy disk, CD-ROM or DVD ROM. The user only receives use of thesoftware that they pay for and the user only has to pay for the actualuse of the software.

It will be clear that modifications and variations can be made to thepresent invention, such as the implementation need not be exactly asdescribed in the above mentioned example, the computer language that theunderlying software is programmed in may be any suitable language, suchas Java, C++ or Visual BASIC. The method of charging and/or billing foruse of the run time licences for the software may vary from thosedescribed above. It is also envisages that the present invention may beapplicable to authorise specified users to access a program, rather thanfor payment of RTLs. Such a security measure to only allow certainpersonnel to access sensitive software applications and is able to tracktheir use.

Such modifications and variations are intended to be within the scope ofthe present invention, the nature of which is to be determined from theforegoing description.

APPENDIX I

 SAIL - API system calls   Login int Login (const char * userName,     const char * userPassword,      const int majorVersion,      constint minorVersion,      const int revisionVersion);

Description

Establishes a login and connection to the Optimiser Online Server. Itverifies the user and application for a login with the Optimiser OnlineServer. This will be the first function call to establish a connectionwith the Optimiser Online Server.

Parameters

Input/ Name Description Output UserName Input, a character stringspecifying the User Input Name. The User name has to be UserPasswordInput, a character string specifying the User Input Password. The Username has to be MajorVersion The application Major Version number InputMinorVersion The application Minor Version number Input RevisionVersionThe application Revision Version number Input

Return Code

int Return an error code or SAIL_SUCCESSFUL for a successful Login. UseGetErrorMessage

to return a message string from the error code.

The developer should test for the following error codes and performcorrective actions.

Error Code Description SAIL WRONGNAMEPASSWORD The user entered the wronguser name and/or password SAIL WRONGUSERNAME The user entered the wronguser name SAIL WRONGUSERPASSWORD The user entered the wrong password

Remarks:

The application should exit or prevent the user to continue if thereturn code is not SAIL_SUCCESSFUL

Example

C++

int errCode; char userName[ ] = “xxxxx”; ′This has to be registered with′ the Optimiser Online Server char userPassword[ ] = “yyyyy”; ′This hasto be registered ′ with Optimiser Online Server int majorVersion = 1;int minorVersion = 2; int revisionVersion = 3; errCode = Login(userName, userPassword,   majorVersion, minorVersion, revisionVersion);if (errCode == 0)  // Logged In Successful else  //logout - Exit Program

Visual Basic

  ′Include into the General declarations section or Module file OptionExplicit Private Declare Function OptimiserLogin Lib “Sail.dll” _  Alias “Login” _  (ByVal userName As String, ByVal userPassword AsString, _    ByVal majorVersion As Long, _    ByVal minorVersion AsLong, _    ByVal revisionVersion As Long _    ) As Long ′Include intothe Form Load section. Dim retVal As Long Dim userName As String DimuserPassword As String userName = “xxxx”  ′This has to be registeredwith the           ′ Optimiser Online Server userPassword = “yyyyyy”′This has to be registered with the           ′ Optimiser Online ServerretVal = OptimiserLogin(userName, userPassword, 1, 1, 1) if (retVal<>SAIL_SUCCESSFUL) Then ′Exit program  IsLoggeIn int IsLoggedln(constint * clpbLoggedln);

Description

Determines whether a login session is currently established.

Parameters

Name Description Input/Output ClpbLoggedln A flag indicates TRUE when aLoggin Output is established and FALS if not.

Return Code

int Return an error code or SAIL_SUCCESSFUL for a successfulOptimiserlsLoggedIn. Use

-   -   GetErrorMessage to return a message string from the error code.

Example

C++

  #define ERR_MESSAGE_LENGTH 255   int errCode, retVal;  BOOL*pbLoggedln = new BOOL;  errCode = IsLoggedIn(pbLoggedIn); if  (errCode!= SAIL_SUCCESSFUL)  {  retVal = GetErrMessage( errCode,      ERR_MESSAGE_LENGTH,       errMsg);    } else {     if(*pbLoggedIn) {      // Optimiser Is Logged In.     } else {      //Optimiser Is not Logged In.     }    }

Visual Basic

  ′Include into the General declarations section or Module file OptionExplicit Private Declare Function OptimiserIsLoggedIn _ Lib “Sail.dll”Alias “IsLoggedIn” (clpbLoggedIn As Long)_As Long ′Include into the FormLoad section. Dim clpbLoggedin As Long  retVal =OptimiserIsLoggedIn(clpbLoggedIn)   If (clpbLoggedIn  FALSE) Then′ Exitprogram

-   -   Logout

int Logout(void);

Description

This terminates the Internet connection to the Optimiser Online Server.This function should be called before the application exit or when allRun Time Licence (RTL) consumptions are completed.

Parameters

None

Return Code

int Return an error code or SAIL_SUCCESSFUL if the Logout wassuccessful. Use

GetErrorMessage to return a message string from the error code.

Example

C++

  Int errCode; errCode = Logout( ); if (errCode == 0)  printf′ “Logout :Successful\n”);

Visual Basic

  ′Include into the General declarations section or Module file OptionExplicit Private Declare Function OptimiserLogout _   Lib “Sail.dll”Alias “Logout” ( ) As Long ′Include into the Form Load section.  iMax =OptimiserLogout( )

-   -   GetErrMessage

int GetErrMessage(int nErrorNum, int iBufferSize, char * constIpszErrorBuf);

Description

This function allows the programmer to retrieve a text stringrepresenting the error code.

Parameters

Input/ Name Description Output nErrorNum The error number returned bythe Optimiser Input Online Server from a previous function callIBufferSize The size allocated for the error message. To Input retrievethe error message length for memory allocation this argument may be setto NULL. LpszErrorBuf A pointer to a character string representingOutput the error code.

Return Code

int Return the length of the error message.

Remarks

This function can be used without a Login connection.

Example

C++

  int errCode; char errMsg[ERR_MESSAGE_LENGTH]; int msgLength; retVal =GetErrMessage( errCode,  ERR_MESSAGE_LENGTH, errMsg); printf(errMsg );

Visual Basic

  ′Include into the General declarations section or Module file OptionExplicit Private Declare Function GetErrorMessage _  Lib “Sail.dll”Alias “GetErrMessage” _  (ByVal errNumber As Long, _   ByVal iBufferSizeAs Long, _   errMessage As String) As Long ′Include into the Form Loadsection Dim retVal As Long Dim iMax As Long Dim strBuffer As String′Return the maximum length of the error message iMax =GetErrorMessage(retVal, 0, ByVal 0&) ′ Allocate space for the buffer andclear it ′with Chr$(0) characters strBuffer = String$(iMax + 1, Chr$(0))′ Call the function again so it can fill strBuffer iMax =GetErrorMessage(retVal, iMax, ByVal strBuffer) ′ Print out the errormessage MsgBox “Error Message is : ” & strBuffer

-   -   CanConsumeRTL

int CanConsumeRTL(int * const clpCanConsume);

Description

Determines whether the current login session has sufficient number ofRTLs in the user's Optimiser Online Server account to warrant furtherconsumption by the calling software application.

Parameters

Input/ Name Description Output ClpCanConsume A return value indicatesTRUE if the Output user may consume some RTL's and FALSE if not.

Return Code

int Return an error code or SAIL_SUCCESSFUL if the CanConsumeRTL wassuccessful. Use

-   -   GetErrorMessage to return a message string from the error code.

Example

C++

  int errCode, retVal; char errMsg[ERR_MESSAGE_LENGTH]; BOOL*clpCanConsumeRTL = new BOOL; errCode = CanConsumeRTL(clpCanConsumeRTL);if (errCode!= SAIL_ SUCCESSFUL) {  retVal = GetErrMessage( errCode,           ERR_MESSAGE_LENGTH,            errMsg); } else {  if(*clpCanConsumeRTL) {   // Can Cansume RTLs.  } else {    // Can NOTcunsume RTLs.  } }

Visual Basic

  ′Include into the General declarations section or Module file OptionExplicit Private Declare Function CanConsumeRTL _   Lib “Sail.dll”(clpYesNo As Long) As Long ′Include into the Form Load section. DimclpYesNo As Long iMax CanConsumeRTL(clpYesNo)  _if clpYesNo = FALSE)Then ′ Exit program

-   -   ConsumeRTI,

int ConsumeRTL (const int nNumberRTLtoConsume, char * constpszComment,);

Description

This operation will debit the currently logged in user's OptimiserOnline Server account with the appropriate amount of RTLs based on thename of the calling software application.

Parameters

Name Description Input/Output nNumberRTLtoConsume Specify the amount ofRTL's to be deducted Input from the users Optimiser Online Serveraccount pszComment A character string supplied by the application Inputas a comment to identify usage. This can be any character string

Return Code

int Return an error code or SAIL_SUCCESSFUL if the ConsumeRTL wassuccessful. Use

-   -   GetErrorMessage to return a message string from the error code.

Remarks:

If return value not SAIL_SUCCESSFUL then further execution shouldterminated.

Example

C++

  #define CONSUME_ONE_RTL 1 char szComment [ ] = “Any Comment”; errCode= ConsumeRTL (CONSUME_ONE_RTL , szComment) ;

Visual Basic

   ′Include into the General declarations section or Module file Option Explicit  Private Declare Function ConsumeRTL Lib “Sail.dll” _  (ByValnConsumeAmount As Long, ByVal pszComment As String)  As Long  ′Includeinto the Form Load section.  Dim retVal As Long  retVal = ConsumeRTL (2,“comment”)   LoginConsumeoneLogout int LoginGonsumeoneLogout( constchar * userName, const char * userPassword, char * const pszComment,const int majorVersion, const int minorVersion, const intrevisionVersion);

Description

A single RTL charge is debited from the user's account for the executionlifetime of the software application being used by the user. Thisfunction login, connect, consume one RTL and close the connection to theOptimiser Online Server.

Parameters

Name Description Input/Output UserName Input, a character stringspecifying the User Name. Input The User name has to be registered withOptimiser Online Server UserPassword Input, a character stringspecifying the User Input Password. The User name has to be registeredwith Optimiser Online server PszGomment A character string supplied bythe application as a Input comment to identify usage. This can be anycharacter string MajorVersion The application Major Version number InputMinorVersion The application Minor Version number Input Revision VersionThe application Revision Version number Input

Return Code

int Return an error code or SAIL_SUCCESSFUL if the LoginConsumeoneLozoutwas successful. Use GetErrorMessage to return a message string from theerror code.

The developer should test for the following error codes and performcorrective actions.

Error Code Description SAIL_WRONGNAMEPASSWORD The user entered the wronguser name and/or password SAIL_WRONGUSERNAME The user entered the wronguser name SAIL_WRONGUSERPASSWORD The user entered the wrong password

Remarks:

The application should exit or prevent the user to continue if thereturn code is not SAIL_SUCCESSFUL.

Example

C++

  int errCode; char userName[ ] “xxxxx”; char userPassword[ ] = “yyyyy”;char pszComment[ ] = “Any Comment”; int majorVersion = 1; intminorVersion = 2; int revisionVersion = 3; errCode =LoginConsumeoneLogout( userName, userPassword,   //Exit program. -Prevent user to continue with   //application  else   // Continue withprogram

Visual Basic

   ′Include into the General declarations section or Module file PrivateDeclare Function LoginConsumeoneLogout Lib “Sail.dll” _   ( ByValuserName As String, ByVal userPassword As String, _    ByVal pszCommentAs String, _    ByVal majorVersion As Long, _    ByVal minorVersion AsLong, _    ByVal revisionVersion As Long _   ) As Long Option ExplicitPrivate Declare Function LoginConsumeoneLogout Lib “Sail.dll” _   (ByVal userName As String, ByVal userPassword As String, _    ByValpszComment As String, _    ByVal majorVersion As Long,__    ByValminorVersion As Long, _    ByVal revisionVersion As Long _   ) As Long′Include into the Form Load section. Dim retVal As Long Dim userName AsString Dim userPassword As String iMax = LoginConsumeoneLogout(userName,     userPassword,     “comment”, 1, 2, 3)

-   -   GetDLLVersion

int GetDLLVersion(int iBufferSize, char * const clpszVersionString,int * const clpiVersionMajor, int *const clpiVersionMinor, int * constclpiVersionRevision);

Description

Returns the version number of this SAIL to the calling softwareapplication. The software application can use this number to keep trackand act accordingly of any interface changes to this system if thissystem is being used in a dynamic environment.

Parameters

iBufferSize The clpszVersionString buffer size supplied by the callingApplication clpszVersionString A character string pointer indicating theversion number of the SAIL. majorVersion SAIL's Major Version numberminorVersion SAIL's Minor Version number revisionVersion SAIL's RevisionVersion number

Return Code

int Return the length of the return message clpszVersionString.

Example

C++

  char *clpszVersionString = new char[225]; int *clpiVersionMajor = newint; int *clpiVersionMinor = new int; int *clpiVersionRevision = newint; int iVersBufferSize = 225; int msgLenght; msgLenght =GetDLLVersion( iVersBufferSize, clpszVersionString, clpiVersionMajor,clpiVersionMinor, clpiVersionRevision);

Visual Basic

' Include into the General declarations section or Module file OptionExplicit Private Declare Function GetDLLVersion Lib “Sail.d11” _  (ByValbufLength As Long,_  clpszVersionString As String _  clpiVersionMajor AsLong, _  clpiVersionMinor As Long, _  clpiVersionRevision As Long _  )As Long ' Include into the Form Load section.

GetTimeOutPeriod

void GetTimeOutPeriod(int * const milliSeconds);

Description

Returns the maximum number of milliseconds to wait for a reply from theOptimiser Online Server before a timeout condition is to be flagged.

Parameters

Input/ Name Description Output MilliSeconds The current set time inmilliseconds to Output wait for a reply from the Online Server before atimeout

Return Code

None

Example

C++

int milliSeconds; int *piMilliSeconds = new int;GetTimeOutPeriod(piMilliSeconds); printf(*piMilliSeconds);

Visual Basic

   ' Include into the General declarations section or Module file OptionExplicit Private Declare Sub GetTimeOutPeriod Lib “Sail.d11” _    (milliSeconds As Long) ' Include into the Form Load section. DimmilliSeconds As Long GetTimeOutPeriod milliSeconds   SetTimeoutPeriod int SetTimeoutPeriod(const unsigned int milliSeconds);

Description

Sets the maximum number of milliseconds to wait for a reply from theOptimiser Online Server before a timeout condition is to be flagged.

Parameters

Input/ Name Description Output milli- Input by the calling Application.Set the maximum Input Seconds number of milliseconds to wait for a replyfrom the Optimiser Online Server before a timeout condition is to beflagged.

Return Code

int Return an error code or SAIL_SUCCESSFUL if the SetTimeoutPeriod wassuccessful. Use

GetErrorMessage to return a message string from the error code.

Example

C++

int errCode; unsigned int milliSeconds; milliSeconds = 15000; errCode =SetTimeoutPeriod(milliSeconds); if (errCode != SAIL_SUCCESSFUL) retVal =GetErrMessage(errCode, ERR_MESSAGE_LENGTH, errMsg);

Visual Basic

' Include into the General declarations section or Module file OptionExplicit Private Declare Sub SetTimeoutPeriod Lib “Sail.d11’_  (ByValmilliSeconds As Long) ' Include into the Form Load section. DimmilliSeconds As Long milliSeconds = 10000 SetTimeoutPeriod milliSeconds

APPENDIX 2 S.A.I.L. Application Programming Interface Definitions

1 SAIL_Login

Prototype

SAILRETCODE SAIL_Login   (   CONST CHAR * CONST szUserName,   CONSTCHAR * CONST szPassword,   CONST CHAR * CONST szProxyUserName,   CONSTCHAR * CONST szProxyPassword,   CONST UNSIGNED INT uiMajorVersion,  CONST UNSIGNED INT uiMinorVersion,   CONST UNSIGNED INTuiRevisionVersion,   CONST CHAR * CONST clpcszApplicationID,   CONSTUNSIGNED INT uiConsumeRTLFreguency,   CONST CHAR * CONSTszConsumeRTLFreguencyComment  ) ;

Description

This operation establishes a connection to the Optimiser Online Serverand attempts to authenticate the user of the software application andthe version number of the Software Application.

Two worker threads could also be created with this operation. The firstthread periodically consumes a single RTL (see parameteruiConsumeRTLFrequency for details). The other thread maintains aheartbeat to keep the connection alive (see the Remarks section belowfor details).

Parameters

Name Direction Description szUserName A pointer to a null-terminatedcharacter string specifying the user name of the user of the SoftwareApplication. The user must be registered with Optimiser Online Server inorder to use the Software Application. This pointer must not be NULLpointer. szPassword A pointer to a null-terminated character stringspecifying the password of the user of the Software Application. Thispointer must not be NULL pointer. szProxyUserName A pointer to anull-terminated character string specifying the proxy user name requiredby a proxy server if applicable. This proxy usemame is company specificand the developer should first set this parameter to a NULL pointer andtest the return code. If the return code is SAIL_PROXY_AUTH_REQUIRED thedeveloper should prompt the user for their proxy user name which is thenused for this parameter in another SAIL Login ( ) operation.szProxyPassword A pointer to a null-terminated character stringspecifying the proxy password required by a proxy server if applicable.This proxy password is company specific and the developer should firstset this parameter to a NULL pointer and test the return code. If thereturn code is SAIL_PROXY_AUTH_REQUIRED the developer should prompt theuser for their proxy password which is then used for this parameter inanother SAIL_Login( ) operation. uiMajorVersion The major versionrelease number of the Software Application. uiMinorVersion The minorversion release number of the Software Application. uiRevisionVersionThe revision version release number of the Software Application.szApplicationID A pointer to a null-terminated character stringspecifying an Application Identifier supplied by Optimiser. This pointermust not be NULL pointer. uiConsumeRTLFrequency This parameter definesthe period in minutes for automated consumption of a single RTL. Thisautomated consumption is implemented in a worker thread. The threadstarts when the user has successfully logged into the Optimiser OnlineServer whereby it enters a loop of consuming a single RTL and thensleeping for the specified period. If consuming a RTL fails, the threadwill issue a call to exit (−1) and terminate the calling SoftwareApplication. The thread will not be created if the value is set to zero.szConsumeRTLFre- A pointer to a null-terminated string containing aquencyComment comment about the RTL transaction being performed by theautomated consumption of RTLs.

Return Value

Returns an error code or SAIL_SUCCESSFUL if the operation wassuccessful. Use SAIL_GetErrorMessage( ) to return a textualrepresentation of the error code.

The developer should test for the following return values and performthe appropriate action:

Error Code Description Action SAIL_SUCCESS The operation was The userhas been authorised to successful. continue to use the SoftwareApplication. The Software Application may now proceed with furtherexecution. SAIL_PROXY_AUTH_REQUIRED The user is required to enter Thedeveloper should prompt the their proxy user name and user for theirproxy username and proxy password details so proxy password. Anotherthat SAIL may instruct the SAIL_Login( ) should be called with proxy toestablish a the parameters szProxyUserName connection to the Optimiserand szProxyPassword set to the data Online Server. entered by the user.SAIL_WRONGNAMEPASSWORD The user entered the wrong The user shouldre-enter the user name and/or password. authentication details.SAIL_APPACCESS DENIED The user does not have The application should exitaccess to this application SAIL_INSUFFICIENT_RTLs_LEFT There areinsufficient The Software Application should RTLs in the user's reportthe error to the user and then account to allow the exit cleanly.Software Application to continue running

The Software Developer should consider any other errors returned by thisoperation as serious failures. The Software Application should reportthe error to the user and then exit cleanly.

Remarks

The Software Application should not proceed further in its executionuntil one of the following conditions has been satisfied:

-   -   The Optimiser Online Server via the SAIL system has verified a        valid username and password pair.    -   The user wishes to cancel the entering of authentication details        into the Software Application to be used by SAIL for        verification, in which case the Software Application should then        exit cleanly.

Once a successful connection to the Optimiser Online Server has beenestablished and the user authorised, then this operation will create upto two worker threads. One thread maintains a heartbeat to keep alive aconnection to the server and the other to periodically consumes RTLsfrom the logged in user's account.

The frequency of the heartbeat can be set with the operationSAIL_SetHeartBeatFrequency( ). The operation SAIL_GetHeartBeatFrequency() can be used to determine the current heartbeat frequency. If thisfrequency is set to zero, then the worker thread that performs theheartbeat will not be created.

The period of the RTL consumption is set through theuiConsumeRTLFrequency parameter. At every period, a single RTL isconsumed and the transaction is recorded with the comment specified inthe szConsumeRTLFrequencyComment parameter.

Examples

C++ Pseudo Code

  #include “SAIL.h” SAILRETCODE RetCode;   // NOTE: The following username and password should be replaced   // with a registered user nameand password supplied from   // Optimiser and should never be hardcoded.The user must   // be provided with a mechanism for entering thesedetails.   CHAR sername[ ] = “xxxxx’; CHAR userPassword[ ] = “yyyyy”;  // NOTE: The following proxy user name and proxy password should  // be replaced with the proxy user name and proxy password  // supplied by the related company administrator and should   // neverbe hardcoded. The user must be provided with a   // mechanism forentering these details.   CHAR userProxyName [ ] “aaaa”;   CHARuserProxyPassword[ ] = “bbbbbb”;   // NOTE: The following indicates theversion release of this   // Application. UINT majorVersion = 1; UINTminorVersion = 2; UINT revisionVersion = 3; // NOTE: The followingApplication ID is an unique identifier // provided by Optimiser. CHARapplicationID[ ] = “zzzzzz”; RetCode = SAIL_Login(    userName,   userPassword,    NULL,    NULL,    majorVersion,    minorVersion,   revisionVersion,    applicationlD,    0,  //Don't start the thread//consumes RTLs periodically    NULL); while (RetCode ==SAIL_PROXY_AUTH_REQUIRED) (  // The SAIL connects to a proxy serverwhich requires a  // proxy user name and proxy password.  //  // NOTE:Prompt user for proxy user name and proxy password  // here and assigntheir entered proxy details to the  // variables userProxyName anduserProxyPassword  // respectively!!! RetCode = SAIL_Login(    userName,   userPassword, userProxyName, userProxyPassword,    majorVersion,minorVersion, revisionVersion, applicationlD,    0,  //Don't start thethread that    //consumes RTLs periodically    NULL); } if (RetCode ==SAIL SUCCESSFUL) {  // The user has now logged into the Optimiser OnlineServer  // and may now proceed with using the application.  } else {  //The login was not successful - handle error condition here. }

Visual Basic Pseudo Code

Option Explicit  Private Declare Function SAIL_Login _     Lib“SAIL.d11” _     (ByVal szUserName As String, _     ByVal szPassword AsString, _     ByVal szProxyUserName As String, _     ByValszProxyPassword As String,_     ByVal uiMajorVersion As Long, _    ByVal uiMinorVersion As Long, _     ByVal uiRevisionVersion As Long,    ByVal szApplicationlD As String, _     ByVal consumeRTLFrequency AsLong, _     ByVal consumeRTLFrequencyComment As String) As Long  DimRetCode As Long  Dim strUserName As String  Dim strPassword As String Dim strProxyUserName As String  Dim strProxyPassword As String  DimstrApplicationlD As String  Dim ConsumeRTLFrequency As Long  DimstrConsumeRTLFrequencyComment As String  ' NOTE: The following user nameand password should be replaced with  ' a registered user name andpassword supplied from Optimiser and  ' should never be hardcoded. Theuser must be provided with a  ' mechanism for entering these details. strUserName = “xxxxx”  strPassword = “yyyyyy”  ' NOTE: The followingproxy user name and proxy password should be  ' replaced with the proxyuser name and proxy password supplied  ' by the related companyadministrator and should never be  ' hardcoded. The user must beprovided with a mechanism for  ' entering these details. strProxyUserName = “aaaa”; strProxyPassword = “bbbbbb”;  ' NOTE: Thefollowing Application ID is an unique identifier  ' provided byOptimiser  strApplicationID = “zzzzzzz”  RetCode SAIL_Login(     strUserName,      strPassword,      ByVal 0&,      ByVal 0&,     App.Major,      App.Minor,      App.Revision, strApplicationID, 0,' Don't start the thread that ' consumes RTLs periodically       ByVal0&)  While ( RetCode = SAIL_PROXY_AUTH_REQUIRED )    ' The SAIL connectsto a proxy server which requires a    ' proxy user name and proxypassword.    ' NOTE: Prompt user for proxy user name and proxy password   ' here and assign their entered proxy details to    ' the variablesuserProxyName and userProxyPassword    ' respectively!!!  RetCode =SAIL_Login(       strUserName,       strPassword,      strProxyUserName,       strProxyPassword,       App.Major,      App.Minor,       App.Revision,       strApplicationID,       0, 'Don't start the thread that ' consumes RTLs periodically       ByVal 0&) Wend  If (RetCode = SAIL_SUCCESSFUL) Then   ' The user has now loggedinto the Optimiser Online Server and   ' may now proceed with using theapplication.  Else   ' The login was not successful - handle errorcondition here.  End If

2 SAIL_IsLoggedln

Prototype

SAILRETCODE SAIL_IsLoggedIn  (  BOOL * CONST clpbLoggedln  );

Description

Determines whether a login session is currently established.

Parameters

Name Direction Description clpbLoggedIn In A pointer to a boolean flag.The contents of the flag will be modified by the operation to indicatewhether a current login session is currently established. This pointermust not be a NULL pointer.

Return Value

Returns an error code or SUCCESSFULSAIL_ if the operation wassuccessful. Use SAIL_GetErrorMessage( ) to return a textualrepresentation of the error code.

Remarks

None

Examples

C++ Pseudo Code

SAILRETCODE RetCode; BOOL bLoggedIn; RetCode =SAIL_IsLoggedIn(&bLoggedIn); if (RetCode == SAIL_SUCCESSFUL) {   if(bLoggedIn) (     // The user is logged in to the Optimiser OnlineServer.  } else {    // The user is not logged in to the OptimiserOnline Server.   }   } else {      // Handle error condition here.  }

Visual Basic Pseudo Code

Option Explicit Private Declare Function SAIL_IsLoggedIn _   Lib“SAIL.d11” (clpbLoggedIn As Long) As Long Dim RetCode As Long DimblnLoggedIn As Long RetCode = SAIL_IsLoggedIn(blnLoggedln) If (RetCode =SAIL_SUCCESSFUL) Then  If (CBool(blnLoggedIn) = True) Then   ' The useris logged in to the Optimiser Online Server. Else   ' The user is notlogged in to the Optimiser Online Server.  End If Else  ' Handle errorcondition here.  End If

3 SAIL_Logout

Prototype

-   -   SAILRETCODE SAIL_Logout ( );

Description

This logs the user out from the Optimiser Online Server. The invocationof this operation should be called to exit cleanly from the OptimiserOnline Server and free any resources SAIL has been allocated with by theunderlying operating system.

Parameters

None

Return Value

Returns an error code or SAIL_SUCCESSFUL if the operation wassuccessful. Use SAIL_GetErrorMessage( ) to return a textualrepresentation of the error code.

The developer should test for the following return values and performthe appropriate action:

Error Code Description Action SAIL_SUCCESS The operation was TheSoftware Application may now successful. proceed with further execution.SAIL_NOTLOGGEDIN The user was not logged No action required. in for thisoperation to be successful.

The Software Developer should consider any other errors returned by thisoperation as serious failures. The Software Application should reportthe error to the user and then exit cleanly.

Remarks

None

Examples

C++ Pseudo Code

SAILRETCODE errCode; RetCode = SAIL_Logout( ); if (RetCode == SAILSUCCESSFUL) {  // The logout from the Optimiser Online Server wassuccessful.  } else {  // The logout from the Optimiser Online Serverwas not  // successful - handle error condition here.  }

Visual Basic Pseudo Code

Option Explicit Private Declare Function SAIL_Logout _ Lib “SAIL.dll” () As Long Dim RetCode As Long RetCode = SAIL_Logout ( ) If (RetCode =SAIL_SUCCESSFUL) Then  ' The logout from the Optimiser Online Server wassuccessful. Else  ' The logout from the Optimiser Online Server was not ' successful - handle error condition here. End If

4 SAIL_GetErrorMessage

Prototype

UNSIGNED INT SAIL_GetErrorMessage  (  CONST SAILRETCODE ErrorNum,  CONSTUNSIGNED INT uiBufferSize,  CHAR * CONST clpszMessageBuffer  );

Description

This operation allows the software developer to retrieve a textualrepresentation of the specified error number.

Parameters

Name Direction Description ErrorNum In The error number as returned froma SAIL operation. uiBufferSize In The size of the message buffer tocontain the corresponding textual representation of the specified SAILerror number. clpszMessageBuffer In A pointer to a buffer to contain anull-terminated string describing the specified SAIL error number. Thepointer can be a NULL pointer.

Return Value

Returns the maximum size required to be able to store the correspondingtextual representation of the specified SAIL error in its entirety.

Remarks

None

Examples

C++ Pseudo Code

SAILRETCODE RetCode; CHAR * szMsg; INT iMsgLength; szMsg = NULL;iMsgLength = 0; // Retrieve the maximum length of the error message.iMsgLength = SAIL_GetErrorMessage(  RetCode,  iMsgLength,  szMsg); //Allocate enough space for the error message and a // terminating nullcharacter. szMsg = new CHAR[iMsgLength + 1]; // Retrieve the errormessage. iMsgLength = SAIL_GetErrorMessage(  RetCode,  iMsgLength, szMsg); // Display the error message to the user. cout << “The SAILError Message is: ” << szMsg << endl; // Free resource. delete [ ]szMsg; szMsg = NULL;

Visual Basic Pseudo Code

Option Explicit Private Declare Function SAIL_GetErrorMessage _ Lib“SAIL.dll”  (ByVal ErrorNum As Long, _   ByVal iBufferSize As Long, _  MessageBuffer As String) As Long Dim RetCode As Long Dim lngMax AsLong Dim strBuffer As String ' Return the maximum length of the errormessage. lngMax = SAIL_GetErrorMessage(RetCode, 0, ByVal 0&) ' Allocatespace for the error message and space for a ' terminating nullcharacter. Clear the space with Chr$(0) ' characters. strBuffer =String$(1ngMax + 1, Chr$(0) ) ' Call the function again so it can fillstrBuffer with the ' error message. lngMax=SAIL_GetErrorMessage(RetCode, lngMax, ByVal strBuffer) ' Print out theobtained error message. MsgBox “The SAIL Error Message is: ” & strBuffer

5 SAIL_CanConsumeRTL

Prototype

  SAILRETCODE SAIL_CanConsumeRTL  (   BOOL * CONST clpbCanConsume  ) ;

Description

Determines whether the current login session has sufficient number ofRTLs in the user's Optimiser Online Server account to warrant furtherconsumption by the calling Software Application.

Parameters

Name Direction: Description clpbCanConsume In A pointer to a booleanflag. The contents of the flag will be modified by the operation toindicate whether there are sufficient RTLs in the user’s account toconsume. This pointer must not be a NULL pointer.

Return Value

Returns an error code or SAIL_SUCCESSFUL if the operation wassuccessful. Use SAIL_GetErrorMessage( ) to return a textualrepresentation of the error code. The Software Developer should considerany errors returned by this operation, other than SAIL_SUCCESSFUL, asserious failures. The Software Application should report the error tothe user and then exit cleanly.

Remarks

None

Examples

C++ Pseudo Code

  SAILRETCODE RetCode; BOOL bCanConsumeRTL; RetCode =SAIL_CanConsumeRTL(&bCanConsumeRTL); if (RetCode == SAIL_SUCCESSFUL) { if (bCanConsumeRTL) {   / / The user is allowed to consume more RTLs. }else {   / / The user can not consume more RTLs.   } } else {  / /Handle error condition here. }

Visual Basic Pseudo Code

  Option Explicit Private Declare Function SAIL_CanConsumeRTL _  Lib“SAIL.dll” (clpbYesNo As Long) As Long Dim RetCode As Long Dim blnYesNoAs Long RetCode = SAIL_CanConsumeRTL(blnYesNo) If (RetCode = SAIL_SUCCESSFUL) Then  If (CBool(blnYesNo) = True) Then   ' The user isallowed to consume more RTLs.   Else   ' The user can not consume moreRTLs.   End If  Else   ' Handle error condition here.   End If

6 SAIL_ConsumeRTL

Prototype

  SAILRETCODE SAIL_ConsumeRTL   CONST UNSIGNED INT uiNumberRTLtoConsume,  CONST CHAR * CONST   szComment  ) ;

Description

This operation will debit the currently logged in user's OptimiserOnline Server account with the appropriate amount of RTLs based on thename of the calling software application.

Parameters

Name Direction Description uiNumberRTLtoConsume In Specify the amount ofRTLs to be deducted from the user’s Optimiser Online Server account.This has an upper limit of 1000. szComment In A pointer to anull-terminated string containing a comment about the RTL transactionbeing performed by this operation. This pointer must not be the NULLpointer.

Return Value

Returns an error code or SAIL_SUCCESSFUL if the operation wassuccessful. Use SAIL_GetErrorMessage( ) to return a textualrepresentation of the error code.

The developer should test for the following return values and performthe appropriate action:

Error Code Description Action SAIL_SUCCESS The operation was TheSoftware Application may successful. now proceed with further execution.SAIL_INSUFFICIENT_RTLs_LEFT There are insufficient The SoftwareApplication should RTLs in the user’s account report the error to theuser and to allow the Software then exit cleanly. Application tocontinue running.

The Software Developer should consider any other errors returned by thisoperation as serious failures. The Software Application should reportthe error to the user and then exit cleanly.

Remarks

The szComment parameter should contain a brief comment about the RTLtransaction being performed. The size of the network packets generatedby this operation to the Optimiser Online Server is dependent upon thelength of this parameter. These network packets should be kept to aminimum size and it is the responsibility of the Software Developer toadopt and maintain this philosophy when invoking this operation.

For this operation to complete successfully, the Software Applicationshould be registered with Optimiser Online. The user should also havesufficient RTLs in their Optimiser Online account. Registration andcrediting a user's account is beyond the scope of this document. Pleasecontact Optimiser for further information regarding these matters

Examples

C++ Pseudo Code

  #define CONSUME_ONE_RTL 1 char szComment[ ] “Some Comment”;SAILRETCODE RetCode; RetCode = SAIL_ConsumeRTL(CONSUME_ONE_RTL,           szComment) ; switch (RetCode) {  case SAIL_SUCCESSFUL:   / /The operation was successful   break;  case SAIL_INSUFFICIENT_RTLs_LEFT   / / The operation was not successful - handle    / / condition here.  break;  default:   / / The operation was not successful - handle   / /error condition here. }

Visual Basic Pseudo Code

  Option Explicit Private Declare Function SAIL_ConsumeRTL _   Lib“SAIL.dll” (ByVal uiConsumeAmount As Long,               ByVal szCommentAs String) As Long Dim RetCode As Long RetCode = SAIL_ConsumeRTL(2,“I've consumed two RTLs here”) Select Case RetCode  Case SAIL_SUCCESSFUL  ' The operation was successful. Case SAIL_INSUFFICIENT_RTLs_LEFT   'The operation was not successful - handle   ' condition here.  Case Else  ' The operation was not successful - handle   ' error condition here.End Select

7 SAIL_LoginConsumeoneLogout

Prototype

  SAILRETCODE SAIL_LoginConsumeoneLogout  (   CONST CHAR * CONSTszUserName,   CONST CHAR * CONST szPassword,   CONST CHAR * CONSTszProxyUserName,   CONST CHAR * CONST szProxyPassword,   CONST CHAR *CONST szComment,   CONST UNSIGNED INT uiMajorVersion,   CONST UNSIGNEDTNT uiMinorVersion,   CONST UNSIGNED INT uiRevisionVersion,   CONSTCHAR * CONST clpcszApplicationID,   CONST UNSIGNED   INTuiConsumeRTLFrequency  ) ;

Description

A single RTL charge is debited from the user's account for the executionlifetime of the software application being used by the user. Thisoperation attempts the following SAIL operations in order:

SAIL_Login(  szUserName,  szPassword,  szProxyUserName, szProxyPassword,uiMajorVersion, uiMinorVersion,  uiRevisionVersion, szApplicationID,uiConsumeRTLFrequency,  szComment) ; SAIL_ConsumeRTL (1, szComment ) ;SAIL_Logout ( ) ;

If either of the above operations fails then this operation failsoverall.

In addition, a worker thread could also be created with this operation.The worker thread periodically consumes a single RTL (see parameteruiConsumeRTLFrequency for details).

Parameters

Name ⁻Direction Description szUserName In A pointer to a null-terminatedcharacter string specifying the user name of the user of the SoftwareApplication. The user must be registered with Optimiser Online Server inorder to use the Software Application. This pointer must not be NULLpointer. szPassword In A pointer to a null-terminated character stringspecifying the password of the user of the Software Application. Thispointer must not be NULL pointer. szProxyUserName In A pointer to anull-terminated character string specifying the proxy user name requiredby a proxy server if applicable. This proxy username is company specificand the developer should first set this parameter to a NULL pointer andtest the return code. If the return code is SAIL_PROXY_AUTH_REQUIRED thedeveloper should prompt the user for their proxy user name which is thenused for this parameter in another SAIL_Login( ) operation. szProxyPassword A pointer to a null-terminated character string specifyingthe proxy password required by a proxy server if applicable. This proxypassword is company specific and the developer should first set thisparameter to a NULL pointer and test the return code. If the return codeis SAIL_PROXY_AUTH_REQUIRED the developer should prompt the user fortheir proxy password which is then used for this parameter in anotherSAIL_Login( ) operation. szComment A pointer to a null-terminated stringcontaining a comment about the RTL transaction being performed by thisoperation. uiMajorVersion The major version release number of theSoftware Application. uiMinorVersion The minor version release number ofthe Software Application. uiRevisionVersion The revision version releasenumber of the Software Application. szApplicationID A pointer to anull-terminated character string specifying an Application Identifiersupplied by Optimiser. This pointer must not be NULL pointer.uiConsumeRTLFrequency This parameter defines the period in minutes forautomated consumption of a single RTL. This automated consumption isimplemented in a worker thread. The thread starts when the user hassuccessfully logged into the Optimiser Online Server whereby it enters aloop of consuming a single RTL and then sleeping for the specifiedperiod. If consuming a RTL fails, the thread will issue a call to exit(−1) and terminate the calling Software Application. The thread will notbe created if the value is set to zero. If this value is set thefunction should be called only once during the lifetime of the SoftwareApplication.

Return Value

Returns an error code or SAIL_SUCCESSFUL if the operation wassuccessful. Use SAIL_GetErrorMessage( ) to return a textualrepresentation of the error code.

The developer should test for the following return values and performthe appropriate action:

Error Code Description Action SAIL_SUCCESS The operation was TheSoftware Application may now successful. proceed with further execution.SAIL_PROXY_AUTH_REQUIRED The user is required to enter The developershould prompt the their proxy user name and user for their proxyusername and proxy password details so proxy password. Another that SAILmay instruct the SAIL_Login ( ) should be called proxy to establish awith the parameters connection to the Optimiser szProxyUserName andOnline Server. sz ProxyPassword set to the data entered by the user.SAIL_WRONGNAMEPASSWORD The user entered the wrong The user shouldre-enter the user name and/or password. authentication details.SAIL_SERVERDENIESREQUEST The Optimiser Online Server The SoftwareApplication should denied the request for report the error to the userand then consuming more RTLs from exit cleanly. the user’s account.Possible causes could be: There are insufficient RTLs in the user’sOptimiser Online account to consume the required amount. The SoftwareApplication is not registered with Optimiser Online.SAIL_APPACCESSDENIED The user does not have The application should exit.access to this application SAIL_INSUFFICIENT_RTLs_LEFT There areinsufficient RTLs The Software Application should in the user’s accountto report the error to the user and then allow the Software exitcleanly. Application to continue running.

The Software Developer should consider any other errors returned by thisoperation as serious failures. The Software Application should reportthe error to the user and then exit cleanly.

Remarks

The szComment parameter should contain a brief comment about the RTLtransaction being performed. The size of the network packets generatedby this operation to the Optimiser Online Server is dependent upon thelength of this parameter. These network packets should be kept to aminimum size and it is the responsibility of the Software Developer toadopt and maintain this philosophy when invoking this operation.

The Software Application should not proceed further in its executionuntil one of the following conditions has been satisfied:

-   -   The Optimiser Online Server via the SAIL system has verified a        valid username and password pair.    -   The user wishes to cancel the entering of authentication details        into the Software Application to be used by SAIL for        verification, in which case the Software Application should then        exit cleanly.

This operation can create a worker thread. The working threadperiodically consumes RTLs from the logged in user's account.

The period of the RTL consumption is set through theuicConsumeRTLFrequency parameter. At every period, a single RTL isconsumed and the transaction is recorded with the comment specified inthe szConsumeRTLFrequencyComment parameter.

Examples

C++ Pseudo Code

#include “SAIL.h” / / NOTE: The following user name and password shouldbe replaced / / with a registered user name and password supplied from // Optimiser and should never be hardcoded. The user must / / be providedwith a mechanism for entering these details. CHAR szUserName [ ]“xxxxx”; CHAR szPassword [ ] “yyyyy”; / / NOTE: The following proxy username and proxy password should / / be replaced with the proxy user nameand proxy password / / supplied by the related company administrator andshould / / never be hardcoded. The user must be provided with a // mechanism for entering these details. CHAR szProxyUserName [ ] =“aaaa”; CHAR szProxyPassword [ ] = “bbbbbb”; SAILRETCODE RetCode; CHARszComment [ ] = “Any Comment”; UINT uiMajorVersion = 1; UINTuiMinorVersion = 2; UINT uiRevisionVersion = 3; / / NOTE: The followingApplication ID is an unique identifier / / which is provide by OptimiserCHAR szApplicationlD = “zzzzzzz” / / NOTE: The following is used toindicate that SAIL should / / automatically consume an RTL every 12hours from login. UINT uiConsumeRTLFrequency = 12 * 60; RetCode =SAIL_LoginConsumeoneLogout(    szUserName,    szPassword,    NULL,   NULL,    szComment,    uiMajorVersion,    uiMinorVersion,   uiRevisionVersion,    szApplicationID,    uiConsumeRTLFrequency);while (RetCode == SAIL PROXY AUTH REQUIRED) {   / / The SAIL connects toa proxy server which requires a   / / proxy user name and proxypassword.   / /   / / NOTE: Prompt user for proxy user name and proxypassword   / / here and assign their entered proxy details to the   // variables userProxyName and userProxyPassword  / / respectively!!!RetCode = SAIL_LoginConsumeoneLogout(    szUserName,    szPassword,   szProxyUserName,    szProxyPassword,    szComment,    uiMajorVersion,   uiMinorVersion,    uiRevisionVersion,    szApplicationID,   uiConsumeRTLFrequency) ; } if (RetCode == SAIL SUCCESSFUL) { / / Theuser has now logged into the Optimiser Online Server and / / may nowproceed with using the application. }else { / / The login was notsuccessful - handle error condition here.  }

Visual Basic Pseudo Code

Option Explicit Private Declare Function SAIL_LoginConsumeoneLogout _  Lib “SAIL.d11” (ByVal szUserName As String, _     ByVal szPassword AsString, _     ByVal szProxyUserName As String, _     ByValszProxyPassword As String, _     ByVal szComment As String, _     ByValuiMajorVersion As Long, _     ByVal uiMinorVersion As Long, _     ByValuiRevisionVersion As Long, _     Byval szApplicationID As String), _    ByVal consumeRTLFrequency As Long) As Long Dim RetCode As Long DimstrUserName As String Dim strPassword As String Dim strProxyUserName AsString Dim strProxyPassword As String Dim strApplicationID As String DIMlngConsumeRTLFrequency As Long  ' NOTE: The following user name andpassword should be replaced with  ' a registered user name and passwordsupplied from Optimiser  ' and should never be hardcoded. The user mustbe provided with  ' a mechanism for entering these details. strUserName= “xxxxx”; strPassword = “yyyyy”;  ' NOTE: The following proxy user nameand proxy password should be  ' replaced with the proxy user name andproxy password  ' supplied by the related company administrator andshould never  be ' hardcoded. The user must be provided with a mechanismfor  ' entering these details. strProxyUserName = “aaaa”;strProxyPassword = “bbbbbb”;  ' NOTE: The following Application ID is anunique identifier which is  ' provide by Optimiser strApplicationlD =“zzzzzzz” ' NOTE: The following is used to indicate that SAIL should' automatically consume an RTL every 12 hours from login.lngConsumeRTLFrequency = 60 * 12 ' Consume RTLs every 12 Hours RetCode =SAIL_LoginConsumeoneLogout(    strUserName, _    strPassword, _    ByVal0&, _    ByVal 0&, _    “a comment”, _    App.Major, _    App.Minor, _   App.Revision,    strApplicationID, _    lngConsumeRTLFrequency) While( RetCode = SAIL_PROXY_AUTH_REQUIRED )   ' The SAIL connects to a proxyserver which requires a proxy   user name   ' and proxy password.   'NOTE: Prompt user for proxy user name and proxy password here and   'assign their entered proxy details to the variables userProxyName   'and userProxyPassword respectively!!! RetCode =SAIL_LoginConsumeoneLogout(    strUserName, _ strPassword, _   strProxyUserName, _    strProxyPassword, _    “a comment”, _App.Major, _    App.Minor, _    App.Revision, _    strApplicationID, _   lngConsumeRTLFrequency) Wend If (RetCode = SAIL_SUCCESSFUL) Then   'The user has now logged into the Optimiser Online Server and   ' may nowproceed with using the application. Else   ' The login was notsuccessful - handle error condition here. End If

8 SAIL_GetDLLVersion

Prototype

  UNSIGNED INT SAIL_GetDLLVersion   (    CONST UNSIGNED INTuiBufferSize,    CHAR * CONST clpszVersionString,    UNSIGNED INT *CONST clpuiVersionMajor,    UNSIGNED INT * CONST clpuiVersionMinor, UNSIGNED INT * CONST clpuiVersionRevision ) ;

Description

Returns the version number of the SAIL library to the calling SoftwareApplication. The Software Application can use this number to keep trackand act accordingly of any interface changes to this system if thissystem is being used in a dynamic environment.

Parameters

Name Direction uiBufferSize The size of the string buffer to contain theSAIL version string. clpszVersionString A pointer to a buffer to containa null-terminated SAIL version string on return from a successful callof this operation. The pointer can be a NULL pointer. clpuiVersionMajorA pointer to an unsigned integer, the contents of which, on return froma successful call of this operation, would indicate the Major Versionnumber of the SAIL library. This pointer can be a NULL pointer.clpuiVersionMinor A pointer to an unsigned integer, the contents ofwhich, on return from a successful call of this operation, wouldindicate the Minor Version number of the SAIL library. This pointer canbe a NULL pointer. clpuiVersionRevision A pointer to an unsignedinteger, the contents of which, on return from a successful call of thisoperation, would indicate the Revision Version number of the SAILlibrary.

Return Value

Returns the maximum size required to be able to store the SAIL versionstring into the buffer in its entirety.

Remarks

None

Examples

C++ Pseudo Code

  #define BUFFERSIZE 225 / / Allocate a static space for the versionstring and a null / / terminating character. CHARszVersionString[BUFFERSIZE + 1]; UINT uiVersionMajor; UINTuiVersionMinor; UINT uiVersionRevision; UINT msgLength; / / RetrieveBUFFERSIZE number of characters of the / / SAIL version string and theversion release of / / the SAIL system. msgLength =SAIL_GetDLLVersion(BUFFERSIZE,               szVersionString,              &uiVersionMajor,               &uiVersionMinor,              &uiVersionRevision);

Visual Basic Pseudo Code

Option Explicit Private Declare Function SAIL_GetDLLVersion  Lib“SAIL.d11” (ByVal uiBufferSize As Long, _ clpszVersionString    AsString, _    clpuiVersionMajor As Long, _ clpuiVersionMinor As    Long,_ clpuiVersionRevision As Long) As Long Dim RetCode As Long Dim lngMaxAs Long Dim strBuffer As String Dim lngMajor As Long Dim lngMinor AsLong Dim lngRevision As Long ' Return the maximum length of the SAILversion string and the ' version release of the SAIL system. lngMax =SAILGetUDLVersion(0,     ByVal 0&,     lngMajor,     lngMinor,    lngRevision) ' Allocate space for the buffer and a null-terminating' character. Clear the buffer with Chr$(0) characters. strBuffer =String$(1ngMax + 1, Chr$(0) ) ' Call the function again so it can fillstrBuffer. lngMax = SAIL_GetDLLVersion(lngMax,    ByVal strBuffer,   ByVal 0&,    ByVal 0&,    ByVal 0&) ' Print out the SAIL versionstring. MsgBox “The SAIL version string is: '“ & strBuffer &”'” & _  vbCrLf &   “The SAIL version is (“ & lngMajor & ”,” & _     lngMinor &”,” & _     lngRevision & ”)”

9 SAIL_GetTimeOutPeriod

Prototype

-   -   UNSIGNED INT SAIL_GetTimeOutPeriod( );

Description

Returns the maximum number of milliseconds to wait for a reply from theOptimiser Online Server before a timeout condition occurs.

Parameters

None

Return Value

Returns the timeout in milliseconds.

Remarks

The default timeout period of 15000 milliseconds is returned if thetimeout period has not been previously set by the SAIL_SetTimeOutPeriod() operation.

Examples

C++ Pseudo Code

  UINT uiMilliSeconds; uiMilliSeconds = SAIL_GetTimeOutPeriod( ); cout<< “The current time out is ” <<  << uiMilliSeconds << “ milliseconds.” << endl;

Visual Basic Pseudo Code

Option Explicit Private Declare Function SAIL_GetTimeOutPeriod _  Lib“SAIL.dll” ( ) As Long Dim lngMilliSeconds As Long lngMilliSeconds =SAIL_GetTimeOutPeriod( ) MsgBox “The current time out period is ” & _ uiMilliSeconds & “ milliseconds.”

10 SAIL_SetTimeOutPeriod

Prototype

VOID SAIL_SetTimeOutPeriod  (   CONST UNSIGNED INT uiMilliSeconds   ) ;

Description

Sets the maximum number of milliseconds to wait for a reply from theOptimiser Online Server before a timeout condition is to be flagged.

Parameters

Name Direction Description uiMilliSeconds In The number of millisecondsto wait for a reply from the Optimiser Online Server before a timeoutcondition occurs. This value must be greater than zero milliseconds. Thedefault is 60 seconds.

Return Value

None

Remarks

The default timeout period is 15000 milliseconds if this operation isnot invoked to set another timeout period.

Examples

C++ Pseudo Code

UINT uiMilliSeconds; uiMilliSeconds = 10000; // 10 second timeout periodSAIL_SetTimeOutPeriod(uiMilliSeconds);

Visual Basic Pseudo Code

Option Explicit Private Declare Sub SAIL_SetTimeOutPeriod _  Lib“SAIL.dll” (ByVal uiMilliSeconds As Long) Dim lngTimeout As LonglngTimeout = 15000 ' 15 second timeout period SAIL_SetTimeOutPeriodlngTimeout

11 SAIL_ChangePassword

Prototype

SAILRETCODE SAIL_ChangePassword   (   CONST CHAR * CONSTszCurrentPassword, CONST CHAR *   CONST   szNewPassword  ) ;

Description

This function allows the user to change his/hers password.

Parameters

Name Direction Description szCurrentPassword In A pointer to anull-terminated character string specifying the current password of theuser. This pointer must not be NULL pointer. szNewPas sword In A pointerto a null-terminated character string specifying the new password forthe user. This pointer must not be NULL pointer.

Return Value

Returns an error code or SAIL_SUCCESSFUL if the operation wassuccessful. Use SAIL_GetErrorMessage( ) to return a textualrepresentation of the error code.

The developer should test for the following return values and performthe appropriate action:

Error Code Description Action SAIL_SUCCESS The operation was TheSoftware Application may successful. now proceed with further execution.SAIL_PASSWORDDENIED The Optimiser Online The Software Application shouldServer denied the request report to the user that the change to changethe password has been denied by the server. SAIL_PASSWORDBAD TheOptimiser Online The Software Application should Server denied therequest report to the user that it is a bad to change the password.password and the change has This might be due to the been denied by theserver. password length or wrong characters used.

Examples

C++ Pseudo Code

// NOTE: The following user passwords should never be hardcoded, // theuser must be provided with a mechanism for entering // these details.CHAR currentPassword [ ] = “xxxxx”; CHAR newPassword [ ] “yyyyy” ;SAILRETCODE RetCode; RetCode = SAILChangePassword(currentPassword;newPassword); if (RetCode == SAIL_SUCCESSFUL) {  // Inform user thatpassword has been changed } else {  // Inform user that password changewas not successful }

Visual Basic Pseudo Code

Option Explicit Private Declare Function SAIL_ChangePassword _  Lib“SAIL.dll” (ByVal currentPassword As String, _ ByVal        newPasswordAs Long) As Long Dim RetCode As Long Dim strNewPassword As String DimstrCurrentPassword As String ′ NOTE: The following user passwords shouldnever be hardcoded, ′   the user must be provided with a mechanism forentering ′  these details. strCurrentPassword = “xxxxx” strNewPassword =“yyyyyy” RetCode = SAIL_ChangePassword(strCurrentPassword,strNewPassword) If (RetCode = SAIL_SUCCESSFUL) Then  ′ Inform user thatpassword has been changed Else  ′ Inform user that password change wasnot successful End If

12 SAIL_SetHeartBeatFrequency

Prototype

VOID SAIL_SetHeartBeatFrequency  (   CONST UNSIGNED INT uiMinutes  ) ;

Description

Sets the frequency to signal the server that the application is stillactive. This signal prevent the disconnection of the network connection.

Parameters

Name Direction Description - uiMinutes In The number of minutes beforesending another signal to the server

Return Value

None

Remarks

The default frequency is 5 minutes if this operation is not invoked toset another frequency period.

The HeartBeat is a separate thread that initiates a message on timeintervals. This HeartBeat thread will not be created if theSAIL_SetHeartBeatFrequency is set to 0 before the SAIL_Login functioncall.

Examples

C++ Pseudo Code

UINT uiSeconds; uiMinutes = 10; // 10 minutesSAIL_SetHeartBeatFrequency(uiMinutes);

Visual Basic Pseudo Code

Option Explicit Private Declare Sub SAIL_ SetHeartBeatFrequency _  Lib“SAIL.dll” (ByVal uiMinutes As Long) Dim lngHeartBeat As LonglngHeartBeat = 10 ′ 10 minutes timeout period SAIL_SetHeartBeatFrequencylngHeartBeat

13 SAIL_GetHeartBeatFrequency

Prototype

-   -   UNSIGNED INT SAIL_GetHeartBeatFrequency( );

Description

Returns the number of minutes to which the HeartBeat is set.

Parameters

None

Return Value

Returns the frequency in minutes.

Remarks

The default frequency of 5 minutes is returned if the frequency has notbeen previously set by the SAIL_SetHeartBeatFrequency( )operation.

Examples

C++ Pseudo Code

UINT uiMinutes; uiMinutes = SAIL_GetHeartBeatFrequency( ); cout << “Thecurrent frequency is ” << uiMinutes << “ minutes.”  << endl;

Visual Basic Pseudo Code

Option Explicit Private Declare Function SAIL_GetHeartBeatFrequency _ Lib “SAIL.dll” ( ) As Long Dim lngMinutes As Long lngMinutes = SAIL_GetHeartBeatFrequency( ) MsgBox “The current time out period is ” & _ lngMinutes & “ minutes.”

14 SAIL_AccountBalance

Prototype

SAILRETCODE SAILAccountBalance   (   UNSIGNED INT * CONSTuiAccountBalance  ) ;

Description

Returns the balance of the Optimiser Online account.

Parameters

Name Description uiAccountBalance In A pointer to an integer thatcontains the Optimiser Online account balance. The content of theinteger will be modified by the operation to the value of the accountbalance. This pointer must not be NULL pointer.

Return Value

Returns an error code or SAIL_SUCCESSFUL if the operation wassuccessful. Use SAIL_GetErrorMessage( ) to return a textualrepresentation of the error code.

Remarks

None

Examples

C++ Pseudo Code

char * userName; char * userPassword; char * proxyUserName; char *proxyPassword; unsigned int majorVersion, minorVersion, revisionVersion;char applicationID[ ] = “abcdefghijklm”; int errCode; unsigned intaccBalance; errCode = SAIL_Login(     userName, userPassword,    proxyUserName, proxyPassword,     majorVersion, minorVersion,revisionVersion,     applicationID,     0, NULL); errCode =SAIL_AccountBalance(&accBalancel); cout << “Account Balance :” <<accBalance << endl;

Visual Basic Pseudo Code

 Option Explicit Private Declare Function SAIL_AccountBalance _  Lib“SAIL.dll” (AccountBalance As Long) As Long Dim lngAccountBalance AsLong errCode = SAIL_AccountBalance(lngAccountBalance) MsgBox “AccountBalance :” & lngAccountBalance

Flag Settings for Compilation and Linking

SAIL is a multi-threaded library and requires the following flag settingat compile time.

1 Windows

Flag Meaning /MD Defines _MT and _DLL so that both multithread andDLL-specific versions of the run-time routines are selected from thestandard .H files. This option also causes the compiler to place thelibrary name MSVCRT.LIB into the .OBJ file. Applications compiled withthis option are statically linked to MSVCRT.LIB. This library provides alayer of code that allows the linker to resolve external references. Theactual working code is contained in MSVCRT.DLL, which must be availableat run time to applications linked with MSVCRT.LIB.

2 SunOS 5

Flag Meaning -mt Specify options needed when compiling multi-threadedcode. -lsocket The socket library required for network calls. -lnsl Thenetwork services library required by lsocket.

3 Notes

Having more than one copy of the run-time libraries in a process cancause problems, because static data in one copy is not shared with theother copy. To ensure that your process contains only one copy, avoidmixing static and dynamic versions of the run-time libraries. The linkerwill prevent you from linking with both static and dynamic versionswithin one .EXE file, but you can still end up with two (or more) copiesof the run-time libraries. For example, a dynamic-link library linkedwith the static (non-DLL) versions of the run-time libraries can causeproblems when used with an .EXE file that was linked with the dynamic(DLL) version of the run-time libraries.

System Settings

1 All Platforms

SAIL can be configured through the setting environment variables priorto executing a SAIL-enabled Software Application. The environmentvariables that SAIL uses are as follows:

System Variable Name Description HTTP_PROXY If the SAIL enabled SoftwareApplication resides behind an HTTP proxy server then setting thisvariable will instruct SAIL to direct communication through thespecified HTTP proxy. The value of this variable should be of the form:<proxy host name>:<proxy port number> Where <proxy host name> is thename of the host acting as proxy and <proxy port number> is the port onwhich the proxy is listening. Example values are:proxy.mydomain.com:8080 192.168.1.1:80 SAIL_HOST_NAME If thisenvironment variable is set then SAIL will establish a connection to thehost specified in the variable’s value. If this variable has not beenset then SAIL will connect to the Optimiser Online Server atsalmon.optimiser.com.au. SAIL_PORT_NUMBER If this environment variableis set then SAIL will establish a connection to the port specified inthe variable’s value. If this variable has not been set then SAIL willconnect to port 80.

2 Windows System Settings

If the HTTP_PROXY environment variable has not been set, then SAIL willdetermine from the Registry whether an enabled HTTP proxy has beenentered for the current user. These settings can be configured throughthe Internet applet found in Control Panel.

If the registry settings do not exist or the proxy setting has beenfound disabled, then SAIL will not use a proxy to establish a connectionto the Optimiser Online Server. SAIL will establish a connection to theOptimiser Online Server directly.

Return Codes

The return codes are listed in the SAIL.H file. The most common errorcodes and their meanings are listed as follows:

Error Code Description SAIL_SUCCESS The operation was successful.SAIL_PROXY_AUTH_REQUIRED The developer should prompt the user for theirproxy username and proxy password. Another SAIL_Login ( ) operationshould be called with the parameters szProxyUserName and szProxyPasswordset to the data entered by the user. SAIL_ALREADYLOGGEDIN The operationfailed because an attempt was made to re- login without logging out thecurrent login session. SAIL_NOTLOGGEDIN The operation failed because alogin session has not been established. SAIL_WRONGNAMEPASSWORD The userentered the wrong user name and/or password. SAIL_SERVERDENIESREQUESTThe Optimiser Online Server denied the request for consuming more RTLsfrom the user’s account. Possible causes could be: There areinsufficient RTLs in the user’s Optimiser Online account to consume therequired amount. The Software Application is not registered withOptimiser Online. SAIL_INSUFFICIENT_RTLs_LEFT There are insufficientRTLs in the user’s account to allow the Software Application to continuerunning.

APPENDIX 3

The following is scenarios of how the SAIL library could be used:

Scenario1—MS Word

MicroSoft could say that people should pay them $1 for every hoursomeone uses the MS Word. They could also say that every time one usesthe Table functionality they should pay two dollars. The implementationof SAIL would be as follows:

-   Step1 At the beginning of the program display a login screen asking    the user for his User Name and Password as registered in the SALMON    server-   Step 2 Use the SAIL_Login api as follows directly after the login    screen    -   errCode=SAIL_Login(userName, userPassword, . . . , . . . , . . .        , . . . , . . . , applicationID,        -   60, “Time charge”);    -   where: userName and UserPassword has been retrieved from the        login screen application ID is a identifier created in SALMON        -   60, “Time charge” this will charge $1 every 60 minutes-   Step3 Validate the return code, errCode, from SAIL_Login.

If it is successful continue with application otherwise callSAIL_ErrMessage to display the Error message. The error message could besomething like “Wrong User Name Password” etc

-   Step4 In the code where it handles the event from “Insert Table” in    MS Word they should insert a SAIL_onsumeRTL api as follows    -   errCode=SAIL_ConsumeRTL(2, “Table Function Used”);    -   where: 2 is the amount of dollars charged for this function and        “Table Function Used” is the information logged in SALMON-   Step5 Validate the return code, errCode, from SAIL_ConsumeRTL.    -   If it is successful continue with application otherwise call        SAIL_ErrMessage to display the Error message. The error message        could be something like “Insufficient funds in account” etc-   Step6 In the code where it handles the event from “File->Exit” in MS    Word they should insert a SAIL_Logout api as follows    -   SAIL_Logout( );

Scenario2—Game

Company ABC Pty(Ltd) develops a game that has different stages which getcharged as following:

Stage 1: Entry Level—No Charge

Stage 2: Charge $2 on entry of this stage 1 and play Unlimited time

Stage 3: Charge $3 on entry of this stage 1 and play Unlimited time

The implementation of SAIL would be as follows:

-   Step1 At the beginning of the program display a login screen asking    the user for his User Name and Password as registered in the SALMON    server.-   Step 2 Use the SAIL_Login api as follows directly after the login    screen    -   errCode=SAIL_Login(userName, userPassword, . . . , . . . , . . .        , . . . , . . . , applicationID,        -   0, NULL);    -   where: userName and UserPassword has been retrieved from the        login screen application ID is a identifier created in SALMON-   Step3 Validate the return code, errCode, from SAIL_Login.    -   If it is successful continue with application otherwise call        SAIL_ErrMessage to display the Error message. The error message        could be something like “Wrong User Name Password” etc-   Step4 In the code where it handles the event from “Start Stage 2” in    games menu they should insert a SAIL_onsumeRTL api as follows    -   errCode=SAIL_ConsumeRTL(2, “Game ABC Stage 2”);    -   where: 2 is the amount of dollars charged to this account for        this stage and “Game ABC Stage 2” is the information logged in        SALMON-   Step5 Validate the return code, errCode, from SAIL_ConsumeRTL.    -   If it is successful continue with application otherwise call        SAIL_ErrMessage to display the Error message. The error message        could be something like “Insufficient funds in account” etc-   Step6 In the code where it handles the event from “Start Stage 3” in    games menu they should insert a SAIL_onsumeRTL api as follows    -   errCode=SAIL_ConsumeRTL(3, “Game ABC Stage 3”);    -   Where: 3 is the amount of dollars charged to this account for        this stage and “Game ABC Stage 3” is the information logged in        SALMON-   Step7 Validate the return code, errCode, from SAIL_ConsumeRTL.    -   If it is successful continue with application otherwise call        SAIL_ErrMessage to display the Error message. The error message        could be something like “Insufficient funds in account” etc-   Step8 In the code where it handles the event from “File->Exit” in    the Game they should insert a SAIL_Logout api as follows    -   SAIL_Logout( );

Scenario3—Accounting Program

Company XYZ Pty(Ltd) developed an accounting package and want to chargepeople $2 per hour usage.

The implementation of SAIL would be as follows:

-   Step1 At the beginning of the program display a login screen asking    the user for his User Name and Password as registered in the SALMON    server.-   Step2 Use the SAIL_LoginConsumeoneLogout api as follows directly    after the login screen    -   errCode=SAIL_LoginConsumeoneLogout(userName, userPassword, . . .        , . . . ,    -   “MYO Accounts” . . . , . . . , . . . , applicationID, 60);    -   where: userName and UserPassword has been retrieved from the        login screen, “MYO Accounts” is a message that is logged on the        server, application ID is a identifier created in SALMON, 60 is        the amount of minutes before he will be charged again.-   Step3 In the code where it handles the event from “File->Exit” in    the Game they should insert a SAIL_Logout api as follows    -   SAIL_Logout( );

1. A method of authorising use of a computer program, said methodcomprising the steps of: providing an authorisation system; recording anidentification of a computer program to be authorised of use by theauthorization system; a user registering with the authorisation systemand receiving a login identification from the authorisation system; theuser making a request to use the computer program; the computer programidentifier and user identification being sent to the authorisationsystem in a login request message; the authorisation system verifyingthe identity of the user from the user login identification and checkingthat the user is authorised to use the computer program identified bythe computer program identifier; the authorisation system recording theinformation sent with the request message; if the user is verified andauthorised to use the computer program, then a login authorizationmessage is sent to the computer program, otherwise an authorisationdenied message is sent to the computer program; whereby upon receipt ofthe authorisation message the computer program may be used by the user.